home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 February: Tool Chest / Dev.CD Feb 00 TC.toast / pc / what's new? / sample code / graphics 3d / setupgl / setupgl.h < prev   
Encoding:
Text File  |  1999-12-18  |  7.7 KB  |  152 lines
  1. /*
  2.     File:        SetupGL.h
  3.  
  4.     Contains:    Functions to enable build and destory a GL fullscreen context
  5.  
  6.     Written by:    Geoff Stahl (ggs)
  7.  
  8.     Copyright:    Copyright © 1999 Apple Computer, Inc., All Rights Reserved
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <4>    12/18/99    ggs     Fix headers
  13.          <3>    11/28/99    ggs     Split out DSp and error handling.  Added texture memory
  14.                                     considerations, assume VRAM is required if other than zero
  15.          <3>    11/12/99    ggs     add pixel format and freq return
  16.          <2>    11/12/99    ggs     1.0 Interface complete
  17.          <1>    11/11/99    ggs     Initial Add
  18.  
  19.     Disclaimer:    IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.
  20.                 ("Apple") in consideration of your agreement to the following terms, and your
  21.                 use, installation, modification or redistribution of this Apple software
  22.                 constitutes acceptance of these terms.  If you do not agree with these terms,
  23.                 please do not use, install, modify or redistribute this Apple software.
  24.  
  25.                 In consideration of your agreement to abide by the following terms, and subject
  26.                 to these terms, Apple grants you a personal, non-exclusive license, under Apple’s
  27.                 copyrights in this original Apple software (the "Apple Software"), to use,
  28.                 reproduce, modify and redistribute the Apple Software, with or without
  29.                 modifications, in source and/or binary forms; provided that if you redistribute
  30.                 the Apple Software in its entirety and without modifications, you must retain
  31.                 this notice and the following text and disclaimers in all such redistributions of
  32.                 the Apple Software.  Neither the name, trademarks, service marks or logos of
  33.                 Apple Computer, Inc. may be used to endorse or promote products derived from the
  34.                 Apple Software without specific prior written permission from Apple.  Except as
  35.                 expressly stated in this notice, no other rights or licenses, express or implied,
  36.                 are granted by Apple herein, including but not limited to any patent rights that
  37.                 may be infringed by your derivative works or by other works in which the Apple
  38.                 Software may be incorporated.
  39.  
  40.                 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO
  41.                 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED
  42.                 WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  43.                 PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN
  44.                 COMBINATION WITH YOUR PRODUCTS.
  45.  
  46.                 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR
  47.                 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  48.                 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  49.                 ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION
  50.                 OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT
  51.                 (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN
  52.                 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  53.  
  54. */
  55.  
  56.  
  57. // Usage notes: 
  58.  
  59.  
  60.  
  61. // include control --------------------------------------------------
  62.  
  63. #ifndef SetupGL_h
  64. #define SetupGL_h
  65.  
  66.  
  67. // includes ---------------------------------------------------------
  68.  
  69. #include <DrawSprocket.h>
  70.  
  71. #include <agl.h>
  72.  
  73.  
  74. // structures (public) -----------------------------------------------
  75.  
  76. struct structGLInfo // storage for setup info
  77. {
  78.     short width;                // input: width of drawable (screen width in full screen mode), return: actual width allocated
  79.     short height;                // input: height of drawable (screen height in full screen mode), return: actual height allocated
  80.     Boolean fSizeMust;            // input: dspContext must be requested display size (ignored in window mode)
  81.                                     // if fSizeMust display size will not be stepped down to try to find a match, 
  82.                                     // if display is stepped down aspect ratio will be maintained for returned size
  83.     short pixelDepth;            // input: requested pixel depth
  84.     Boolean fDepthMust;            // input: pixel depth must be set (if false then current depth will be used if able)
  85.     Boolean fFullscreen;        // input: use DSp to get fullscreen? (or find full screen renderer)
  86.                                     // if fFullscreen, will search for full screen renderers first then use DSp for others
  87.                                     //  unless a device is specified, in which case we will try there first
  88.     Boolean fAcceleratedMust;     // input: must renderer be accelerated?
  89.     GLint aglAttributes[64];     // input: pixel format attributes always required (reset to what was actually allocated)
  90.     long VRAM;                    // input: minimum VRAM; output: actual (if successful otherwise input)
  91.     long textureRAM;            // input: amount of texture RAM required on card; output: same (used in allcoation to ensure enough texture
  92.     AGLPixelFormat    fmt;        // input: none; output pixel format...
  93.     int freq;                    // input: frequency request for display; output: actual
  94. };
  95. typedef struct structGLInfo structGLInfo;
  96. typedef struct structGLInfo * pstructGLInfo;
  97.  
  98. // structure fro creating a context from a window
  99. struct structGLWindowInfo // storage for setup info
  100. {
  101.     Boolean fAcceleratedMust;     // input: must renderer be accelerated?
  102.     GLint aglAttributes[64];     // input: pixel format attributes always required (reset to what was actually allocated)
  103.     long VRAM;                    // input: minimum VRAM; output: actual (if successful otherwise input)
  104.     long textureRAM;            // input: amount of texture RAM required on card; output: same (used in allcoation to ensure enough texture
  105.     AGLPixelFormat    fmt;        // input: none; output pixel format...
  106. };
  107. typedef struct structGLWindowInfo structGLWindowInfo;
  108. typedef struct structGLWindowInfo * pstructGLWindowInfo;
  109.  
  110. // public function declarations -------------------------------------
  111.  
  112. // Takes device # and geometry request and tries to build best context and drawable
  113. //     If requested device does not work, will start at first device and walk down devices 
  114. //     looking for first one that satisfies requirments
  115. //  Devices are numbered in order that DMGetFirstScreenDevice/DMGetNextScreenDevice returns, 
  116. //     fullscreen devices are numbered after this, but they will be searched first if fFullscreen == true,
  117. //     they will not be searched in the non-fullscreen case
  118.  
  119. // Inputs:     *pnumDevice: -1: main device, 0: any device, other #: attempt that device first, then any device
  120. //            *pcontextInfo: request and requirements for cotext and drawable
  121.  
  122. // Outputs: *paglDraw, *paglContext and *pdspContext as allocated
  123. //            *pnumDevice to device number in list that was used 
  124. //            *pcontextInfo:  allocated parameters
  125.  
  126. // If fail to build context: paglDraw, paglContext and pdspContext will be NULL
  127. // If fatal error: will return error and paglDraw, paglContext and pdspContext will be NULL
  128. // Note: Errors can be generated internally when a specific device fails, this is normal and these
  129. //          will not be returned is a subsequent device succeeds
  130. OSStatus BuildGL (AGLDrawable* paglDraw, AGLContext* paglContext, DSpContextReference* pdspContext, 
  131.                   short* pnumDevice, pstructGLInfo pcontextInfo);
  132.                   
  133. // Destroys drawable and context
  134. // Ouputs: *paglDraw, *paglContext and *pdspContext should be 0 on exit
  135. OSStatus DestroyGL (AGLDrawable* paglDraw, AGLContext* paglContext, DSpContextReference* pdspContext, pstructGLInfo pcontextInfo);
  136.  
  137.  
  138. // same as above except that it takes a window as input and attempts to build requested conext on that
  139. OSStatus BuildGLFromWindow (AGLDrawable aglDraw, AGLContext* paglContext, pstructGLWindowInfo pcontextInfo);
  140.  
  141. // same as above but destorys a context that was associated with an existing window, window is left intacted
  142. OSStatus DestroyGLFromWindow (AGLContext* paglContext, pstructGLWindowInfo pcontextInfo);
  143.  
  144.  
  145. // Pauses gl to allow toolbox drawing
  146. OSStatus PauseGL (AGLContext aglContext);
  147.  
  148. // resumes gl to allow gl drawing
  149. OSStatus ResumeGL (AGLDrawable aglDraw, AGLContext aglContext);
  150.  
  151.  
  152. #endif // SetupGL_h